🔗 Redirect URIs Added to Logto

The following redirect URIs have been automatically added to the Logto application configuration:

Redirect URIs:

• https://my-proxy-qa-pr-47.onrender.com/login-redirect

Post-logout redirect URIs:

• https://my-proxy-qa-pr-47.onrender.com/login

These will be automatically removed when the PR is closed or merged.

🤖 My API structural change detected

Preview documentation

Powered by Bump.sh

tunnel-client binary (linux/amd64)

Download:

tunnel-client.zip

Quick start

# Make it executable
chmod +x tunnel-client-linux-amd64

# Run it
./tunnel-client-linux-amd64 \
  --url wss://my-proxy-qa-pr-47.onrender.com/support/api/tunnel \
  --key <SYSTEM_KEY> \
  --secret <SYSTEM_SECRET>

Parameters

Service discovery modes

The tunnel-client auto-detects the environment:

• NS8: discovers services from Redis + Traefik routes
• NethSecurity: discovers services from OpenWrt/nginx config
• Static: define services manually with --static-services

Diagnostics plugin system

At connect time, the tunnel-client collects a health snapshot and sends it to MY over the tunnel. Operators see the results directly in the support session popover — before opening a terminal or proxy — so they have immediate context on the system state.

How it works:

1. When the tunnel-client starts, it runs all diagnostic plugins in parallel with the WebSocket connection (no delay to the connection itself)
2. After sending the service manifest, it waits up to --diagnostics-total-timeout (default 30s) for the plugins to finish, then pushes the aggregated report over a dedicated yamux stream
3. The support service stores the report on the session; MY shows it in the session popover

Built-in plugin (system): always runs regardless of configuration. Collects:

• OS name and version (from /etc/os-release)
• CPU load averages (1m / 5m / 15m from /proc/loadavg)
• RAM usage (from /proc/meminfo, warning >85%, critical >95%)
• Root disk usage (warning >85%, critical >95%)
• System uptime

External plugins: any executable file placed in /usr/share/my/diagnostics.d/ is run automatically. Files are executed in alphabetical order, each with its own timeout. This allows NS8 modules, NethSecurity, and third-party integrations to ship their own health checks independently.

Each plugin must:

• Write a JSON object to stdout
• Signal severity via exit code: 0 = ok, 1 = warning, 2 = critical

#!/bin/bash
# /usr/share/my/diagnostics.d/10-myservice.sh

STATUS="ok"
SUMMARY="all good"

if ! systemctl is-active --quiet myservice; then
  STATUS="critical"
  SUMMARY="myservice is not running"
fi

echo "{\"id\":\"myservice\",\"name\":\"My Service\",\"status\":\"$STATUS\",\"summary\":\"$SUMMARY\"}"
exit $([ "$STATUS" = "ok" ] && echo 0 || echo 2)

The overall session status shown in MY is the worst status across all plugins (critical > warning > ok). If a plugin exceeds its timeout it is marked timeout and does not block the others.

If --diagnostics-dir points to a directory that does not exist, only the built-in system plugin runs — no error, no configuration needed on systems that have not installed any plugins yet.

Environment variables

All flags can also be passed as env vars:

export SUPPORT_URL=wss://my-proxy-qa-pr-47.onrender.com/support/api/tunnel
export SYSTEM_KEY=<your-key>
export SYSTEM_SECRET=<your-secret>
./tunnel-client-linux-amd64

Plugin Systems: diagnostics.d/ and users.d/

The tunnel-client supports two extensible plugin directories. Both follow the same security model but serve different purposes. This comment is a reference for developers integrating new plugins.

diagnostics.d/ — System Health Checks

Path: /usr/share/my/diagnostics.d/ (configurable via DIAGNOSTICS_DIR or --diagnostics-dir)

Purpose: Each plugin reports health status of a specific subsystem. Results are aggregated into a diagnostics report visible in the support session UI.

Execution model:

• Plugins are executables (any language: bash, python, Go binary, etc.)
• Invoked with no arguments, no stdin
• Must write a JSON PluginResult to stdout (or raw text as fallback)
• Exit code determines status: 0 = ok, 1 = warning, 2 = critical, other = error
• Timeout: 10s default (configurable via DIAGNOSTICS_PLUGIN_TIMEOUT)
• Output limit: 512 KB stdout

Output format (JSON on stdout):

{
  "id": "my-plugin",
  "name": "My Plugin",
  "status": "ok|warning|critical",
  "summary": "optional summary text",
  "checks": [
    { "name": "check_name", "status": "ok", "value": "42", "details": "optional" }
  ]
}

If JSON parsing fails, the raw stdout text becomes the summary field and status is derived from the exit code.

Built-in plugin: system always runs (CPU load, RAM, disk, uptime) — it's hardcoded, not a file.

users.d/ — Application Configuration for Support Users

Path: /usr/share/my/users.d/ (configurable via USERS_DIR or --users-dir)

Purpose: After the tunnel-client provisions ephemeral support users (cluster-admin + domain users on NS8, local admin on NethSecurity), plugins in users.d/ configure applications to accept those credentials. For example, the nethvoice plugin creates a FreePBX ampusers entry so the support user can log in to NethVoice.

Execution model:

• Plugins are executables invoked with two actions: setup and teardown
• Arguments: <action> --users-file /path/to/users.json [--instances-file /path/to/instances.json]
• --users-file contains the full SessionUsers JSON (credentials, platform, session info)
• --instances-file is provided only if the plugin name matches a discovered NS8 module base name (e.g., plugin nethvoice matches modules nethvoice103, nethvoice104)
• Timeout: 15s default (configurable via USERS_PLUGIN_TIMEOUT)
• Output limit: 64 KB stdout

--users-file format (SessionUsers):

{
  "session_id": "uuid",
  "platform": "nethserver|nethsecurity",
  "cluster_admin": { "username": "support-neth-xxxx-yyyy", "password": "..." },
  "domain_users": [
    { "domain": "sf.nethserver.net", "module": "openldap1", "username": "support-neth-xxxx-yyyy", "password": "..." }
  ],
  "local_users": [
    { "username": "support-neth-xxxx-yyyy", "password": "..." }
  ],
  "module_domains": { "nethvoice103": "sf.nethserver.net" },
  "created_at": "2026-03-24T..."
}

--instances-file format (ModuleContext):

{
  "module": "nethvoice",
  "instances": [
    {
      "id": "nethvoice103",
      "node_id": "1",
      "label": "Main PBX",
      "domain": "sf.nethserver.net",
      "services": {
        "nethvoice103-wizard": { "host": "127.0.0.1", "path_prefix": "/nethvoice103-wizard", "tls": true }
      }
    }
  ]
}

setup output (JSON on stdout) — array of AppConfig:

[
  {
    "id": "nethvoice103",
    "name": "NethVoice (Main PBX)",
    "url": "optional direct URL",
    "notes": "Domain: sf.nethserver.net | Service: nethvoice103-wizard"
  }
]

These AppConfig entries appear in the support session UI so operators know which applications are configured and how to access them.

teardown: Called when the session ends (or tunnel-client shuts down). Must undo whatever setup did (delete users, revoke access). Stdout is ignored.

Shared Security Model (both plugin types)

Both diagnostics.d/ and users.d/ apply identical security checks before executing a plugin:

If any check fails, the plugin is silently skipped with a log message.

Plugin Naming Convention (users.d only)

The plugin filename determines module matching:

• If a plugin is named nethvoice, the tunnel-client checks if any discovered NS8 module has base name nethvoice (stripping trailing digits: nethvoice103 → nethvoice)
• If a match is found, --instances-file is passed with all matching instances, their domains, labels, node IDs, and service routes
• If no match is found, the plugin runs without --instances-file (useful for generic plugins that don't need module context)

This enables a single nethvoice plugin to configure all NethVoice instances on the cluster.

Example: Adding a New users.d Plugin

To add support user configuration for a new NS8 module (e.g., webtop):

1. Create /usr/share/my/users.d/webtop (executable, owned by root, mode 0755)
2. Handle setup and teardown actions
3. Read credentials from --users-file (domain user matching the instance's domain)
4. Read instance context from --instances-file (module instances, services, domains)
5. Output AppConfig JSON array on stdout during setup

See examples/users.d/nethvoice in this PR for a complete reference implementation.